<!DOCTYPE html>
<html>
  <head>
    <meta name="creator" content="mantohtml v2.0.2">
    <title>client.conf(5)</title>
  </head>
  <body>
    <h1 id="client.conf-5">client.conf(5)</h1>
    <h2 id="client.conf-5.name">Name</h2>
<p>client.conf - client configuration file for cups (deprecated on macos)
</p>
    <h2 id="client.conf-5.description">Description</h2>
<p>The <strong>client.conf</strong> file configures the CUPS client and is normally located in the <em>/etc/cups</em> and/or <em>~/.cups</em> directories.
Each line in the file can be a configuration directive, a blank line, or a comment. Comment lines start with the # character.
</p>
    <p><strong>Note:</strong> macOS applications can access many of these settings in the <em>/Library/Preferences/org.cups.PrintingPrefs.plist</em> file instead.
macOS also does not support the
<strong>ServerName</strong>
directive.
See the NOTES section below for more information.
</p>
    <h3 id="client.conf-5.description.directives">Directives</h3>
<p>The following directives are understood by the client. Consult the online help for detailed descriptions:
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>AllowAnyRoot Yes</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>AllowAnyRoot No</strong><br>
Specifies whether to allow TLS with certificates that have not been signed by a trusted Certificate Authority.
The default is &quot;Yes&quot;.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>AllowExpiredCerts Yes</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>AllowExpiredCerts No</strong><br>
Specifies whether to allow TLS with expired certificates.
The default is &quot;No&quot;.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>BrowseDomains all</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>BrowseDomains none</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>BrowseDomains </strong><em>DOMAIN[,...,DOMAIN]</em><br>
Specifies the DNS-SD domains to browse for IPP printers.
The value &quot;all&quot; browses the &quot;.local&quot; domain (mDNS) and all registered DNS domains on the local system.
The value &quot;none&quot; disables browsing for network printers.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>DigestOptions DenyMD5</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>DigestOptions None</strong><br>
Specifies HTTP Digest authentication options.
<strong>DenyMD5</strong> disables support for the original MD5 hash algorithm.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>Encryption IfRequested</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>Encryption Never</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>Encryption Required</strong><br>
Specifies the level of encryption that should be used.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>FilterLocation </strong><em>LOCATION[,...,LOCATION]</em><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>FilterLocation </strong><em>'LOCATION'[,...,'LOCATION']</em><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>FilterLocation </strong><em>&quot;LOCATION&quot;[,...,&quot;LOCATION&quot;]</em><br>
Specifies a list of locations to use for destinations.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>FilterLocation </strong><em>/REGULAR-EXPRESSION/</em><br>
Specifies a regular expression for matching locations to use for destinations.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>FilterType any</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>FilterType </strong><em>TYPE[,...,TYPE]</em><br>
Specifies the type of destinations to use.
The TYPE values are &quot;mono&quot; for B&amp;W printers, &quot;color&quot; for color printers, &quot;duplex&quot; for printers with 2-sided printing capabilities, &quot;simplex&quot; for printers with 1-sided printing capabilities, &quot;bind&quot; for printers that can bind output, &quot;cover&quot; for printers that can cover output, &quot;punch&quot; for printers that can punch output, &quot;sort&quot; for printers that can sort output, &quot;staple&quot; for printers with a stapler, &quot;small&quot; for printers that support media up to US Legal/ISO A4, &quot;medium&quot; for printers that support media up to US Tabloid/ISO A3, and &quot;large&quot; for printers that support media larger than US Tabloid/ISO A3.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>GSSServiceName </strong><em>name</em><br>
Specifies the Kerberos service name that is used for authentication, typically &quot;host&quot;, &quot;http&quot;, or &quot;ipp&quot;.
CUPS adds the remote hostname (&quot;name@server.example.com&quot;) for you. The default name is &quot;http&quot;.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ServerName </strong><em>hostname-or-ip-address</em>[<em>:port</em>]<br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ServerName </strong><em>/domain/socket</em><br>
Specifies the address and optionally the port to use when connecting to the server.
<strong>Note: This directive is not supported on macOS 10.7 or later.</strong>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ServerName </strong><em>hostname-or-ip-address</em>[<em>:port</em>]<strong>/version=1.1</strong><br>
Specifies the address and optionally the port to use when connecting to a server running CUPS 1.3.12 and earlier.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>SSLOptions </strong>[<em>AllowDH</em>] [<em>AllowRC4</em>] [<em>AllowSSL3</em>] [<em>DenyCBC</em>] [<em>DenyTLS1.0</em>] [<em>MaxTLS1.0</em>] [<em>MaxTLS1.1</em>] [<em>MaxTLS1.2</em>] [<em>MaxTLS1.3</em>] [<em>MinTLS1.0</em>] [<em>MinTLS1.1</em>] [<em>MinTLS1.2</em>] [<em>MinTLS1.3</em>]<br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>SSLOptions None</strong><br>
Sets encryption options (only in /etc/cups/client.conf).
By default, CUPS only supports encryption using TLS v1.0 or higher using known secure cipher suites.
Security is reduced when <em>Allow</em> options are used.
Security is enhanced when <em>Deny</em> options are used.
The <em>AllowDH</em> option enables cipher suites using plain Diffie-Hellman key negotiation (not supported on systems using GNU TLS).
The <em>AllowRC4</em> option enables the 128-bit RC4 cipher suites, which are required for some older clients.
The <em>AllowSSL3</em> option enables SSL v3.0, which is required for some older clients that do not support TLS v1.0.
The <em>DenyCBC</em> option disables all CBC cipher suites.
The <em>DenyTLS1.0</em> option disables TLS v1.0 support - this sets the minimum protocol version to TLS v1.1.
The <em>MinTLS</em> options set the minimum TLS version to support.
The <em>MaxTLS</em> options set the maximum TLS version to support.
Not all operating systems support TLS 1.3 at this time.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>TrustOnFirstUse Yes</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>TrustOnFirstUse No</strong><br>
Specifies whether to trust new TLS certificates by default.
The default is &quot;Yes&quot;.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>User </strong><em>name</em><br>
Specifies the default user name to use for requests.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>UserAgentTokens None</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>UserAgentTokens ProductOnly</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>UserAgentTokens Major</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>UserAgentTokens Minor</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>UserAgentTokens Minimal</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>UserAgentTokens OS</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>UserAgentTokens Full</strong><br>
Specifies what information is included in the User-Agent header of HTTP requests.
&quot;None&quot; disables the User-Agent header.
&quot;ProductOnly&quot; reports &quot;CUPS&quot;.
&quot;Major&quot; reports &quot;CUPS/major IPP/2&quot;.
&quot;Minor&quot; reports &quot;CUPS/major.minor IPP/2.1&quot;.
&quot;Minimal&quot; reports &quot;CUPS/major.minor.patch IPP/2.1&quot;.
&quot;OS&quot; reports &quot;CUPS/major.minor.path (osname osversion) IPP/2.1&quot;.
&quot;Full&quot; reports &quot;CUPS/major.minor.path (osname osversion; architecture) IPP/2.1&quot;.
The default is &quot;Minimal&quot;.
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ValidateCerts Yes</strong><br>
</p>
    <p style="margin-left: 2.5em; text-indent: -2.5em;"><strong>ValidateCerts No</strong><br>
Specifies whether to only allow TLS with certificates whose common name matches the hostname.
The default is &quot;No&quot;.
</p>
    <h2 id="client.conf-5.x.509-certificate-store">X.509 Certificate Store</h2>
<p>CUPS uses the system root CA certificate store and per-user certificate stores managed by CUPS.
The per-user certificate stores are found in &quot;/etc/cups/ssl&quot; for the root user and &quot;$XDG_CONFIG_HOME/cups/ssl&quot; (Linux/*BSD), &quot;$HOME/Library/Application Support/cups/ssl&quot; (macOS), &quot;%USERPROFILE%/AppData/Local/cups&quot; (Windows), and/or &quot;$HOME/.cups/ssl&quot; for other user accounts.
</p>
    <p>Certificates, certificate signing requests, and private keys are stored as PEM-encoded files with the naming convention &quot;COMMON-NAME.crt&quot; for certificates, &quot;COMMON-NAME.csr&quot; for certificate signing requests, and &quot;COMMON-NAME.key&quot; for private keys. The special common name &quot;_site_&quot; is used for a site-specific root certificate that can be used for trust evaluations.
</p>
    <h2 id="client.conf-5.x.509-certificate-validation">X.509 Certificate Validation</h2>
<p>CUPS supports validation of the certificate's commonName and subjectAltName field values, the certificate expiration date, and the certificate's root certificate(s), if any.
Self-signed certificates are &quot;pinned&quot; (stored) to the host in order to do validation.
Validation for certain non-printing servers may add additional restrictions to the policy defined in the
<strong>client.conf</strong>
file, for example OAuth authorization requires a CA-signed certificate.
</p>
    <p>The
<strong>AllowAnyRoot</strong>
directive controls whether unpinned self-signed certificates are acceptable.
The
<strong>TrustOnFirstUse</strong>
directive controls whether self-certificates are automatically pinned in the per-user certificate store for subsequent host validations.
When
<strong>AllowAnyRoot</strong>
is disabled,
<strong>TrustOnFirstUse</strong>
is also disabled.
</p>
    <h2 id="client.conf-5.notes">Notes</h2>
<p>Because of sandboxing, the <strong>client.conf</strong> file is not generally accessible to applications on macOS.
Configuration settings can instead be viewed or changed using the
<strong>defaults</strong>(1)

command:
</p>
    <pre>defaults write /Library/Preferences/org.cups.PrintingPrefs.plist Encryption Required
defaults write /Library/Preferences/org.cups.PrintingPrefs.plist TrustOnFirstUse -bool NO

defaults read /Library/Preferences/org.cups.PrintingPrefs.plist Encryption
</pre>
<p>On Linux and other systems using GNU TLS, the <em>/etc/cups/ssl/site.crl</em> file, if present, provides a list of revoked X.509 certificates and is used when validating certificates.
</p>
    <h2 id="client.conf-5.see-also">See Also</h2>
<a href="cups.html"><p><strong>cups</strong>(1)</a>

</p>
    <h2 id="client.conf-5.copyright">Copyright</h2>
<p>Copyright &copy; 2021-2025 by OpenPrinting.
  </body>
</html>
